in my mind, we should first forward the overflow event, and after that, start the simulation. so a user might be able to recognize simulated events?

Hm, this could be useful, but it seems quite nontrivial to implement (but I'm maybe overthinking/misunderstanding the idea). Two issues:

• The generation of synthetic events runs asynchronously on the executor, similar to how it currently works in JDKRecursiveDirectoryWatcher. I think that's in principle a reasonable choice. However, it could mean that between the original overflow event and the synthetic events, concurrent/unrelated "actual" events come in.
• Even if there's no interference, there's currently no way of telling how many synthetic events are to be expected.

If we want to support this, then a more reliable approach could be to tag WatchEvent objects as ORIGINAL or SYNTHETIC(i), where i is some kind of an overflow identifier (to be able to distinguish incoming synthetic events that belong to different overflow events, e.g., when they happen shortly after each other). For now, I propose to make a GI issue for this to remember, but not yet implement it, because: (a) it's a cool feature but unclear how much needed; (b) there's already a workaround available, namely, for the programmer to just implement their own overflow handler. What do you think?

I meant: chain the simulator after the forwarder, instead of now, first sinulate then forward.

The chain consists of:

• MemorylessRescanner: Asynchronously simulates CREATED/MODIFIED events and forwards them to eventHandler
• eventHandler: User-defined event-handler that does the actual event-handling work

Changing the order isn't needed to achieve the intended effect (also covered by this test).

Hmm, I'm a bit confused. I mean that from a client perspective I want us to make sure that on an overflow, the overflow events get send to the client first, and only after that is send do we start sending simulated events.

And maybe this is happening already? But when reading the code I thought: should it not be:

return eventHandler.andThen(new MemorylessRescanner(executor))

but I have to admit I'm missing a bit of context of the eventHandler code.

Ah, ok, that's what you intend to achieve 🙂! Yes, we can enforce that, but as a client, I don't think it makes a difference, because it can't distinguish simulated events from regular events (see also previous comment), regardless of whether the overflow comes first, last, or anywhere in between. I don't see any harm in your proposed change either, though, so now that I understand the intension behind it, I'll change it and merge.